home *** CD-ROM | disk | FTP | other *** search
/ SPACE 1 / SPACE - Library 1 - Volume 1.iso / telecomm / 576 / xyz2 / xyz.doc < prev    next >
Text File  |  1978-02-04  |  45KB  |  1,031 lines
  1.                           STARFALL SOFTWARE PRESENTS
  2.                                XYZ version 2.0
  3.                                ===============
  4.                                By Alan Hamilton
  5.                    Copyright (C) 1990, all rights reserved
  6.  
  7.  
  8. 1 WHAT IT IS
  9.  
  10. Here it is.... all you need for transferring files with your ST. I was
  11. frustrated by the limitations that the ST version of RZ.TTP and SZ.TTP had, so
  12. I wrote my own, and I'm willing to fix any bugs that turn up in it.
  13.  
  14. XYZ version 2.0 is SHAREWARE and copyrighted.  You may freely pass it around
  15. and post it on private or public BBSs.  If you like it, please help out by
  16. making a contribution.  I suggest $10, but if you think XYZ is worth less, or
  17. more, send whatever you think is fair.  The previous version, v1.43, is not
  18. copyrighted and still free, so if it serves your needs, feel free to continue
  19. using it.
  20.  
  21. Send comments, contributions, etc. to:   Alan Hamilton
  22.                                          6202 N. 16th St. #202
  23.                                          Phoenix, AZ  85016-1734
  24.  
  25.  
  26. Features include:
  27. 1.  Transfers all files unchanged -- "binary" mode.
  28. 2.  Transfers files at the maximum speed the system you are connected to can
  29. support.  No "wait states."
  30. 3.  The timestamps on the files are preserved, unless you don't want them to
  31. be.  You are told, in regular calendar format, what the timestamp is.
  32. 4.  Interrupted transfers can be restarted where they left off (in ZMODEM).
  33. 5.  You are kept informed as to how much of the file has actually been
  34. received, not how many bytes have been received in the current session.  If
  35. you tried to restart a transfer with RZ.TTP, you wouldn't know where you
  36. were.
  37. 6.  There is no feature six.
  38. 7.  Filenames that aren't compatible with the ST are transformed into ones
  39. that are, not just truncated at the first illegal character.  If they can't be
  40. converted, a random filename is chosen.  These transformed filenames are
  41. unique -- no more losing a file because after being truncated because it was
  42. the same as a previous filename.
  43. 8.  Works with all ST, STe and Mega ST configurations.
  44. 9.  Includes versions of XMODEM and YMODEM for completeness.
  45.  
  46.  
  47. 2  LEGAL STUFF
  48.  
  49. XYZ is copyright (C) 1990 by Alan Hamilton, all rights reserved.  It may be
  50. copied and distributed freely provided that the XYZ.TTP, XYZ.DOC, and READ.ME
  51. files are all included.  If distributed for a fee, it should be made clear to
  52. the purchaser that the fee does not include the shareware fee (see above).
  53.  
  54. XYZ is shareware.  If you use XYZ, please register it.  I suggest a $10
  55. registration fee, but if you think it's worth more, or less, send that
  56. amount.
  57.  
  58. Although I've done my best to test XYZ, it's offered "as is" with no guarantee
  59. at all.  You use it at your own risk.  I will not be responsible for any
  60. losses you may suffer from using it.
  61.  
  62.  
  63. 3  ACKNOWLEDGMENTS
  64.  
  65. XMODEM was developed by Ward Christenson.
  66. YMODEM and ZMODEM were developed by Chuck Forsberg of Omen Technology.
  67. CRC code by Stephen Satchell of Satchell Evaluations, and Chuck Forsberg of
  68. Omen Technology.
  69. Flash is a trademark of Antic Publishing.
  70. C library code copyright (C)1988 by the Mark Williams Company.
  71. 520ST, 1040ST, STe, Mega ST and Mega STe are trademarks of Atari, Inc.
  72. GEnie is a trademark of GEISCO/General Electric.
  73. GEM and GEM Desktop are trademarks of Digital Research.
  74.  
  75. 4  WHAT IT ISN'T
  76.  
  77. Although XYZ supports the most useful parts of the ZMODEM protocol, there are
  78. a few things that aren't.
  79.  
  80. 1.  Commands.  This part of the ZMODEM protocol was intended to allow you to
  81. remotely control a system.  Since XYZ is intended to be manually operated, and
  82. the ST doesn't have a standard command line interface, commands are not
  83. accepted.
  84. 2.  Compression.  Neither run-length encoding (RLE) nor Lempel-Ziv-Welch (LZW)
  85. compression is supported.  You can use a separate utility to compress files
  86. and then send them with XYZ if you want.
  87. 3.  Challenges.  XYZ does not try to verify that it is connected to a system
  88. that is ready for ZMODEM.  It assumes that you have already told that system
  89. to go to ZMODEM.
  90. 4.  Pathnames.  XYZ does not send any path information to the remote system,
  91. and strips off any it receives.
  92. 5.  Selective file replacement.  The ZMODEM protocol lets you selectively
  93. transfer files based on whether they exist or don't exist at the receiver, or
  94. whether they are different in file size, date, or CRC.  XYZ only does one of
  95. two things while downloading:  If a file does not exist, it is transferred in
  96. its entirety.  If it does exists, it assumes that you are resuming a file
  97. transfer that was aborted, and tries to resume at the end of what you have.
  98. When uploading, the remote system will decide which files to accept.
  99. 6.  File transmission resumption.  Do not try to download a file that already
  100. exists on your disk unless you are trying to recover an aborted transfer.  The
  101. file will be damaged if it is a different file, despite having the same name.
  102. If the file was previously received in its entirety, and you try to restart a
  103. download on it, it probably won't be damaged, but this depends on how the
  104. sender reacts, so be careful.
  105. 7.  Disk space check.  If the sender tries to check on how much space you have
  106. available on your disk, XYZ will always tell it that you have an unlimited
  107. amount.  This was done because checking the disk space is a very slow
  108. operation on hard drives.
  109. 8.  Encrypting.  File encryption is not supported.
  110. 9.  Seven bit transfers.  Transferring eight bit files (non-text files) over
  111. lines that only support seven bits per character is not supported.  This is
  112. something you'd only run into with a mainframe.
  113. 10.  Sparse files.  Transferring selected portions of a file that's mostly
  114. zeros is not supported.  The entire file must be sent.
  115. 11.  32 bit CRCs.  XYZ only uses 16 bit CRCs, which should be sufficient
  116. unless you are really paranoid about data integrity.
  117. 12.  CRC checks on files.  Some systems will do this to determine whether or
  118. not they have the same version of a file as the one you are sending.  XYZ
  119. doesn't support this check at this time.
  120.  
  121. 5  HOW TO USE IT
  122.  
  123. 5.1  Configuration
  124. XYZ is mainly intended to be run from inside a regular telecommunications
  125. terminal program.  Because of this, it does not alter the settings of your
  126. ST's RS232 port from what the terminal program has set them to.  For XYZ the
  127. RS232 port should be set as follows:
  128.  
  129. Baud (or bits per second or BPS):
  130. This should match what the system you are connecting with requires, and what
  131. your modem is capable of.
  132. Data bits:     8
  133. Parity:        None
  134. Stop bits:     1 or 2
  135. Flow control:  XOFF/XON (also called DC2/DC4):  OFF
  136.                RTS/CTS:  OFF, unless you are using a high-speed modem that
  137. requires it to be on.
  138.  
  139. These settings are very common, so you probably won't have to change them.
  140.  
  141. 5.2  Running from the Desktop
  142. If you can't run programs from within your terminal program, or your memory
  143. space is limited, you will have to exit to the Desktop to run XYZ.  Set the
  144. remote system up for the transfer, then exit your terminal program.  Open XYZ,
  145. and a dialog box will appear.  Type in the options (see below for the options
  146. available), click on OK, and the transfer will start.  One of the options you
  147. will want to specify is -p which will make XYZ pause before it returns to the
  148. GEM Desktop.  If you don't specify a folder to download to, the files will go
  149. into the same folder that XYZ is in.  After XYZ finishes, it will exit back to
  150. the Desktop.  You may then rerun your terminal program and continue.
  151.  
  152. If you can run programs from within your terminal program, life gets much
  153. easier.  If, however, your terminal program doesn't let you pass parameters to
  154. a .TTP program, you will only be able to download only with ZMODEM and to the
  155. default folder.  See the manual for your terminal program for directions on
  156. running other programs.
  157.  
  158. In Flash, the command is "exec xyz.ttp" (omit the quote marks).  Any options
  159. go after the program name.  If you are keeping XYZ in a different folder than
  160. the default one (set with Flash's DP or CD commands), you will have to specify
  161. it:  "exec c:\telecom\xyz.ttp".  You can even program a function key to run
  162. XYZ, and download with the push of one button.  Program the key you want with
  163. ">exec xyz.ttp|", along with any options you want before the |.  (See the
  164. Flash manual on setting function keys.)  After XYZ completes, you will be
  165. returned to Flash.
  166.  
  167. 5.3  Aborting a transfer
  168. If you want to stop a transfer before it is complete, press the UNDO key.  XYZ
  169. will send an abort sequence to the remote system and terminate.  Keep in mind
  170. that some mainframes take their own sweet time responding to abort sequences,
  171. so you may see a long string of garbage on your screen, or the mainframe may
  172. seem to have locked up.  If you are using ZMODEM, you can restart the transfer
  173. of a partially transferred file later.
  174.  
  175. 5.4  Second chance file save
  176. In case of a disk error while saving a downloaded file, XYZ will give you a
  177. second chance to save the file, with the limitation that the entire file must
  178. fit in XYZ's buffer, and that you respond to the error message within 30
  179. seconds.  The time delay only applies to your first response.  After that, XYZ
  180. will wait any amount of time for your input.  To cancel the time out, press
  181. any key.
  182.  
  183. You have three options.
  184.  
  185. Retry save, selected by typing 'R', makes XYZ try the operation again.  If the
  186. problem that caused the first failure hasn't been fixed, the error will happen
  187. again.
  188.  
  189. New path, selected by typing 'N', lets you enter a different folder or drive
  190. to save to. For example, to save to the root directory of drive B:, you'd
  191. enter "B:\" (without the quote marks).  If you select a path that doesn't
  192. exist, you will get another error.
  193.  
  194. Abort, selected by typing 'A', makes XYZ abort the save.  You will lose
  195. anything that was in XYZ's buffer, and the file transfer will be aborted.
  196. If you don't respond to the error message within 30 seconds, XYZ will choose
  197. Abort for you.  This happens so that if XYZ is running unattended, it won't
  198. get stuck.
  199.  
  200. 5.5  Downloading
  201. 5.5.1  ZMODEM
  202. The -z option selects ZMODEM, but since this is what XYZ defaults to, the -z
  203. may be omitted.  You can specify a folder to download to on the command line.
  204. If you don't specify a folder, XYZ will put the files in the current default
  205. folder.  This is either the folder that XYZ was run from or the folder your
  206. terminal program was run from, unless you've explicitly changed it with
  207. something like Flash's DP command.
  208.  
  209. Examples:                           No options means download ZMODEM
  210.                                     to the default folder
  211.           c:\download               Download ZMODEM to the DOWNLOAD folder
  212.                                     on drive C:
  213.  
  214. 5.5.2  YMODEM
  215. The -y option selects the YMODEM batch protocol.  You should know that some
  216. BBSs call XMODEM-1K (XMODEM with 1K blocks) "YMODEM," and call YMODEM "YMODEM
  217. batch."  If the system offers both those options, select YMODEM batch to use
  218. with XYZ's YMODEM.
  219.  
  220. You can specify a folder to download to on the command line.  If you don't
  221. specify a folder, XYZ will put the files in the current default folder.  This
  222. is either the folder that XYZ was run from or the folder your terminal program
  223. was run from, unless you've explicitly changed it with something like Flash's
  224. DP command.
  225.  
  226. Examples:  -y                        Download YMODEM to the default folder
  227.            -y c:\download            Download YMODEM to the DOWNLOAD folder
  228.                                      on drive C:
  229.  
  230. 5.5.3  XMODEM
  231. The -x option selects an XMODEM file transfer.  You should know that some BBSs
  232. call XMODEM-1K (XMODEM with 1K blocks) "YMODEM," and call YMODEM "YMODEM
  233. batch."  If the system offers both those options, select YMODEM to use with
  234. XYZ's XMODEM with 1K blocks, or XMODEM to use with XYZ's XMODEM with 128 byte
  235. blocks.
  236.  
  237. XMODEM does not provide a way for the remote system to tell XYZ what the name
  238. of the file being transferred is, so you must put the file name on the command
  239. line.  If you want the file to go into a folder other than the default one,
  240. you should specify the path name also.  See the examples below.
  241.  
  242. You do not need to tell XYZ if the remote system will be using 1K blocks or
  243. not.  XYZ will get that information by itself from the other system.
  244.  
  245. If you want to transfer an XMODEM file from a very old system that is still
  246. using the original XMODEM with checksum error checking, use the -xc option
  247. instead of -x on the command line.  You should only use this if it's all the
  248. system will support.  The newer CRC error checking is much more reliable.
  249.  
  250. Examples:  -x forbush.txt          Download with XMODEM the file FORBUSH.TXT
  251.                                    to the default folder
  252.            -x a:\pdq\phred.txt     Download with XMODEM the file PHRED.TXT
  253.                                    to the PDQ folder on drive A:
  254.            -xc oldfile.txt       Download with XMODEM using checksum error
  255.                                    detection the file OLDFILE.TXT
  256.  
  257. 5.6  Uploading
  258. 5.6.1  Wildcards
  259. When uploading with YMODEM or ZMODEM, you can transfer more than one file at
  260. once.  You can put the names of the files to send on the command line, but you
  261. are limited by the length of the line, and in any case, XYZ will only take 10
  262. filenames that way.  By using wildcards, you can give XYZ a partial filename,
  263. and it will upload all the filenames that match it.
  264.  
  265. The two wildcard characters are ? and *.  The question mark will match exactly
  266. one character, and the asterisk will match zero, one, or more characters.
  267. Suppose you have the following files on your disk:
  268.  
  269. THING1.PRG
  270. THING2.PRG
  271. THING.PRG
  272. THING44.TXT
  273.  
  274. THING?.PRG would match THING1.PRG and THING2.PRG.  THING*.PRG would match
  275. THING1.PRG, THING2.PRG, and THING.PRG.  *.TXT would match THING44.TXT only.
  276. The wildcard combination *.* will match all of them.  You should be careful
  277. about using *.*, as it will send every file in the folder, including XYZ,
  278. should it be in that folder.
  279.  
  280. 5.6.2  ZMODEM
  281. The options -u -z select ZMODEM uploading.  ZMODEM is the default, so you can
  282. just specify -u if you want.  Place the filenames of the files you want to
  283. transfer (up to ten) on the command line.  Wildcards are allowed, and XYZ will
  284. send every file that matches, even if there are more than ten files.
  285.  
  286. Examples:  -u c:\uploads\*.*        Upload using ZMODEM every file in the
  287.                                     UPLOADS folder on drive C:
  288.            -u file1 file2           Upload using ZMODEM FILE1 and FILE2 from
  289.                                     the default folder
  290.            -u a:\*.arc              Upload using ZMODEM every ARC file in
  291.                                     the root directory of drive A:
  292.  
  293. 5.6.3  YMODEM
  294. The options -u -y select YMODEM uploading.  You should know that some BBSs
  295. call XMODEM-1K (XMODEM with 1K blocks) "YMODEM," and call YMODEM "YMODEM
  296. batch."  If the system offers both those options, select YMODEM batch to use
  297. with XYZ's YMODEM.
  298.  
  299. Place the filenames of the files you want to transfer (up to ten) on the
  300. command line.  Wildcards are allowed, and XYZ will send every file that
  301. matches, even if there are more than ten files.
  302.  
  303. Examples:  -u -y c:\uploads\*.*   Send using YMODEM all the files in the
  304.                                   UPLOADS folder on drive C:
  305.            -u -y file1 file2      Send using YMODEM FILE1 and FILE2 from
  306.                                   the default folder
  307.            -u -y a:\*.arc         Send using YMODEM all the ARC files from
  308.                                   the root directory of drive A:
  309.  
  310. 5.6.4  XMODEM
  311. The options -u -x select XMODEM uploading.  Using the option -x1k instead of
  312. -x makes XYZ use 1K blocks rather than the default 128 byte blocks.  1K blocks
  313. make the transfer go faster, but the remote system has to support them.  You
  314. should know that some BBSs call XMODEM-1K (XMODEM with 1K blocks) "YMODEM,"
  315. and call YMODEM "YMODEM batch."  If the system offers both those options,
  316. select "YMODEM" to use with XYZ's XMODEM with 1K blocks, or "XMODEM" to use
  317. 128 byte blocks.
  318.  
  319. You don't need to tell XYZ whether to use CRC or checksum error detection
  320. while uploading.  It will get that information directly from the remote
  321. system.
  322.  
  323. XMODEM can only transfer one file per session.  Put the name of the file to
  324. send on the command line.  If you use wildcards, only the first file that
  325. matches will be sent.  This may be any one of the matching files, and there's
  326. no good way to tell in advance which one it will be.  Using wildcards with
  327. XMODEM is *not* recommended for this reason.
  328.  
  329. Examples:  -u -x snowball.arc    Send using XMODEM the file SNOWBALL.ARC
  330.                                  from the default folder
  331.            -u -x1k ako.gif     Send using XMODEM-1K the file AKO.GIF
  332.                                  from the default folder
  333.            -u -x1k a:\b\c.arc  Send using XMODEM-1K the file C.ARC
  334.                                  from the B folder on drive A:
  335.  
  336.  
  337. 5.7  Options
  338. 5.7.1  -a  Alarm
  339. Normally, XYZ will ring the terminal bell when it has completed transferring
  340. all the selected files.  Putting -a on the command line makes XYZ ring the
  341. bell after each and every file.
  342.  
  343. 5.7.2  -b  Baud rate
  344. This does NOT set the baud rate of your modem port.  This sets the rate that
  345. XYZ bases its transfer times on.  You only need to use this if you are using a
  346. non-standard baud rate, like 14,400, or if XYZ cannot determine the correct
  347. baud rate on your model of ST.  Setting a rate of 0 disables the transfer time
  348. messages.  There must not be any spaces between the -b and the speed.
  349. Example:  -b14400       Base transfer times on 14,400 baud
  350.           -b0           Disable transfer time messages.
  351.  
  352. 5.7.3  -h  Help
  353. This causes a short description of the available options to print out, along
  354. with the current version number.  Giving an invalid option gets you this
  355. display, too.
  356.  
  357. 5.7.4  -p  Pause
  358. If you are running XYZ from the Desktop, you won't be able to see any error
  359. messages when it exits, as the Desktop wipes them out.  Putting -p on the
  360. command line will make XYZ prompt you to press a key before it exits.
  361.  
  362. 5.7.5  -r<n>   Set retry limit
  363. Ordinarily, XYZ will abort a transfer if more than ten errors occur.  When you
  364. have had that many errors, the chances of an error slipping through undetected
  365. become greater.  If, however, you want to take your chances, you can set the
  366. retry limit with this command.  It can be set anywhere from the default 10 up
  367. to 1000.  There must not be any spaces between the -r and the number.
  368. Example:  -r50     Set XYZ's retry limit to 50
  369.  
  370. 5.7.6  -s  Return status
  371. This option is only useful if you are having some other program call up XYZ.
  372. The -s option makes XYZ return a status code that indicates how the file
  373. transfer went.  Use this only with a program that expects XYZ to return status
  374. codes.  See the error messages section for details on what the errors mean.
  375. The codes are:
  376.   0  No error
  377.  -1  Missing block number
  378.  -2  Missing or bad header
  379.  -3  Synchronization error
  380.  -4  Timed out
  381.  -5  Checksum error
  382.  -6  User aborted
  383.  -7  File error
  384.  -8  Too many retries
  385.  -9  CRC error
  386. -10  Filename must be specified
  387. -11  Bad escape character
  388. -12  Bad or unsupported packet type
  389. -13  Bad hexadecimal character
  390. -14  Sender not ready or set to receive
  391. -15  Subpacket too long
  392. -16  Sender aborted
  393. -17  File position error
  394. -18  Sender indicates end of file, but file length is wrong
  395. -19  Receiver canceled
  396. -20  End of transmission not acknowledged
  397. -21  Bad option on command line
  398. -22  Not enough memory to allocate buffers
  399.  
  400. 5.7.7  -t  Touch
  401. This makes XYZ "touch" (set the time and date to the current time and date)
  402. files that it downloads.  If the sender specifies a creation time and date for
  403. a file, that is normally retained.  The -t option makes XYZ use the current
  404. time and date instead.  If the creation time and date isn't specified by the
  405. sender, the current time and date is put on the file.  XMODEM will always use
  406. the current time and date.
  407.  
  408. 5.7.8  -v<file>  Verbose mode
  409. This causes XYZ to output special debugging information.  If no file is
  410. specified, the output goes to the screen.  If a file is specified, it should
  411. be directly after the "v" (no spaces), and output will go to it, along with
  412. any error messages you might get.  If you have problems with XYZ, run it with
  413. the -v option, and send the file it creates along with any comments to me.
  414. When using a file, there must not be any spaces between the -v and the file
  415. name.
  416. Examples:  -v             Download ZMODEM, sending debug info to screen
  417.            -ve:\log.txt   Download ZMODEM, sending debug info to "log.txt"
  418.                           on drive E:
  419.  
  420.  
  421. 6  PROBLEMS
  422. If you have problems with XYZ, look up the error messages here in the manual.
  423. If you can't resolve your problems using that information, run it using the
  424. -vlog.txt command, and send the log.txt, along with any other information that
  425. seems relevant, to me on the GEnie computer service, at either A.HAMILTON1 or
  426. STARFALL.  You can also contact me at the mail address given at the start of
  427. this document.
  428.  
  429.  
  430. 7  REVISION HISTORY
  431.  
  432. 11-19-90:  v2.0:  I knew I'd get back to it eventually.
  433. New command line options:
  434.  -u  (upload)  Yes, uploading is here finally!
  435.  -s  (status)  If you are running XYZ from another program, like a BBS, you
  436. can have XYZ return error codes.
  437.  -b  (baud rate) sets rate that file transfer times are based on.  See below.
  438. New features:
  439.     Transfer time estimation.  XYZ will estimate the time it will take to send
  440. a file, based on the speed that the serial port is set at, or on the rate you
  441. specify with the -b option.
  442.     Second chance save.  If XYZ encounters a disk error while saving a file,
  443. and the file will fit entirely within XYZ's buffer, XYZ will give you a second
  444. chance to save it.
  445.     Bugs relating to changing incompatible filenames have been fixed.  The -v
  446. option no longer has to be the last one on the command line.  YMODEM doesn't
  447. bomb on some errors anymore.  ZMODEM handles resending packets better.
  448. Sometimes you would get a GEM dialog box in response to a disk error, but the
  449. mouse was disabled so you couldn't select anything.  XYZ now handles its own
  450. errors.
  451.  
  452. 12-6-89:  v1.43:  More bug fixes!  When trying to rename some incompatible
  453. filenames, XYZ would bomb.  If you tried to download more than one file in a
  454. ZMODEM session, and the first file was a restarted transfer (already partially
  455. downloaded), the characters per second speed rating would be wrong on
  456. subsequent files.  A new option "-a" has been added.  This will make the
  457. terminal bell ring after every file in YMODEM and ZMODEM, not just at the end
  458. of a complete session.  XYZ now shows its version and creation date whenever
  459. you run it.  A byte count is now shown along with the block count in XMODEM
  460. and YMODEM.  XMODEM and YMODEM can now recover from a timeout error on the
  461. first block.  XMODEM and YMODEM now will retry the correct number of times; it
  462. was only retrying half as many as it should have.  A few typos have been fixed
  463. in the program and this doc file (how come nobody told me "transferred" had
  464. two r's?).
  465.  
  466. 11-3-89:  v1.42:  In 1.41, if you were disconnected while using ZMODEM, XYZ
  467. would not time out, and you would not be able to use the UNDO key to abort.
  468. The only way out would be to reset the computer.  The console bell now rings
  469. at the end of a file transfer session.
  470.  
  471. 10-21-89:  v1.41:  Lots o' changes this time:
  472. 1.  If v1.3 of XYZ was started before the sender started up, XYZ would bomb.
  473. Fixed.
  474. 2.  A bug in handling of file creation dates in YMODEM has been fixed.
  475. 3.  XMODEM and YMODEM now use disk buffering.
  476. 4.  File errors are now more explicit as to what the problem is.
  477. 5.  ZMODEM now can handle speeds over 9600 baud.
  478. 6.  XMODEM and YMODEM now indicate how fast the files were transferred.
  479. ZMODEM no longer overstates the transfer rate if you are restarting a
  480. transfer.
  481. 7.  Handling of retries is different.  In earlier versions, the retry limit
  482. (before aborting) was supposed to be ten, but a bug made it only five.  This
  483. has been fixed, and a new option has been added to let you specify a retry
  484. limit.  Put -r<n> on the command line, with <n> replaced by the number of
  485. retries (up to 1000).  For example, -r25 would give you 25 retries.
  486. 8.  Some messages that were similar in YMODEM and ZMODEM were changed to be
  487. exactly the same.
  488. 9.  Some of the C library code has been replaced with code of my own, making
  489. XYZ about 4k smaller.
  490.  
  491. 10-1-89:  v1.3  At long last, disk buffering is here!  Rather than saving
  492. after every packet, XYZ only does a disk write after all available memory has
  493. been filled up.  XYZ now lets you start it before the sender has started.
  494. This was attempted in v1.2, but a bug in the code would make XYZ bomb if you
  495. tried it.  That has been fixed.  A disk full condition is now reported, rather
  496. than just a generic "File error" if the disk doesn't have enough room for the
  497. file.  A new option -p will make XYZ wait for you to press a key before
  498. exiting.  This can be handy if you are running XYZ from the Desktop.
  499.  
  500. 9-19-89:  v1.2  Up to now, if XYZ got five CTRL-X's while waiting for a ZMODEM
  501. frame to start, it would abort with a "Sender aborted" error.  Now it only
  502. aborts if it gets five *consecutive* CTRL-X's.  Unexpected aborts most often
  503. happened during recovery of CRC errors.  Now sends hardware break signal
  504. correctly.  XYZ now handles timeout errors better.
  505.  
  506. 9-15-89:  v1.1:  A rather stupid error regarding filename conversion has been
  507. fixed.  XYZ would sometimes insert a '.' in the seventh or eighth position of
  508. a filename, regardless of whether it was appropriate or not.  The help screen
  509. (printed in response to the -h option) has been rearranged.
  510.  
  511. 9-13-89:  XYZ v1.0 released.  Implements ZMODEM for the first time.  Buffer
  512. overflow at high bps rates fixed.  Synchronization error in YMODEM fixed
  513. (again!).  UNDO key handling improved.  The documentation file, XYZ.DOC, is
  514. totally new.  XY.DOC is no longer applicable.
  515.  
  516. 7-2-89:  XY.TTP v0.5 released.  Handles only XMODEM and YMODEM.  Early release
  517. to accommodate changes made to GEnie software that Flash(tm) could not
  518. handle.
  519.  
  520.  
  521. 8  ERROR MESSAGES
  522.  
  523. Something that has always ticked me off is getting an error message from the
  524. program I'm using, looking it up in the manual, and finding that IT'S NOT
  525. THERE!  So, what follows is a complete listing, in alphabetical order, of
  526. every possible message that XYZ can produce, along with an explanation.
  527.  
  528. Access denied
  529. The ST could not open a file either because the file is set to read only
  530. status, or a folder exists with that same name.
  531.  
  532. Attn string:  <hex bytes>
  533. This details the string the sender wants XYZ to use to interrupt it.
  534.  
  535. Average transfer rate = <number> cps
  536. This gives the average throughput in characters per second.
  537.  
  538. Bad escape char <hex byte>
  539. An invalid escape sequence was received.  Probably caused by line noise.
  540.  
  541. Bad escape character
  542. An invalid escape sequence was received.  Probably caused by line noise.
  543.  
  544. Bad hexadecimal character
  545. XYZ was expecting a hexadecimal digit but got an character that wasn't 0-9 or
  546. a-f.  Probably caused by line noise.
  547.  
  548. Bad option on command line
  549. An option that XYZ doesn't recognize was in the command line.
  550.  
  551. Bad or unsupported packet type
  552. An unrecognized packet was received.  Either caused by line noise, the sender
  553. being set to upload when XYZ is downloading or vice versa, or using ZMODEM
  554. features XYZ doesn't support.  See "WHAT IT ISN'T" section.
  555.  
  556. Bad packet type <number>
  557. Same as above.  The type number of the packet is printed.
  558.  
  559. Bad request
  560. A serious error within either the ST's operating system or within XYZ has
  561. occurred.  You may have to reset your computer.
  562.  
  563. Bombs
  564. Not the word "Bombs", but the little cartoon bombs on the left side of your
  565. screen.  The ST's processor has encountered an instruction that it can't
  566. process.  This can be caused by a bad copy of XYZ, a conflict with a desk
  567. accessory or program in the AUTO folder, or (most likely) a coding  boo-boo of
  568. mine.
  569.  
  570. Block #<block number>  (<number> bytes, <speed> cps)
  571. Number of the block being received, the number of bytes already transferred,
  572. and the number of characters per second that were transferred for this block.
  573.  
  574. Block resent, but not requested.
  575. A block was retransmitted that XYZ did not request.  Caused either by line
  576. noise, or very slow responses by the sender.
  577.  
  578. Buffer size = <size>, serial port speed = <speed>
  579. The number of bytes of memory that XYZ will use as a buffer, and the speed
  580. that your modem port is set at.
  581.  
  582. <number> bytes (<number> cps)
  583. Indicates how much of file has been transferred, and how many characters per
  584. second were transferred for this block.
  585.  
  586. Can't convert filename "<filename>", will use "<filename>"
  587. The sender specified a filename that XYZ couldn't make compatible with the
  588. Atari ST's operating system.  A random filename with the extension .XYZ will
  589. be used.
  590.  
  591. Can't find any files matching "<filename>"
  592. XYZ couldn't find one of the files you specified for uploading, or if you used
  593. wildcards, there were no matching files.  Make sure that the filename is
  594. correct, and that you've specified the path if the file isn't in the default
  595. folder
  596.  
  597. Can't open error log
  598. The filename specified with the -v (verbose) option can't be opened.  The
  599. output will go to the screen instead.
  600.  
  601. Caught a <number> signal
  602. The remote system is interrupting XYZ's upload with the indicated packet
  603. type.
  604.  
  605. Checksum error
  606. The checksum on the last block was invalid.  Probably caused by line noise.
  607.  
  608. Command received, but commands not supported
  609. XYZ does not accept commands from remote systems.  See "WHAT IT ISN'T"
  610. section.
  611.  
  612. Command: <command>
  613. Text of command received.  See above.
  614.  
  615. CRC error
  616. The CRC error detection code on the last block was invalid.  Probably caused
  617. by line noise.
  618.  
  619. Crc error (as part of file error message)
  620. The ST detected an error while accessing the disk.  The disk may be damaged.
  621.  
  622. Disk full!
  623. There isn't enough room on your disk to hold the file.  The transfer is
  624. aborted, with as much of the file as the disk will hold saved.  You can resume
  625. the transfer in ZMODEM if you move the partial file to another disk that has
  626. more room, or if you delete some files on the disk.  If the entire file fits
  627. in the disk buffer, you can use the second chance save feature to save it to a
  628. different disk.
  629.  
  630. Downloading YMODEM
  631. A YMODEM session has started.
  632.  
  633. Drive not ready
  634. The disk drive isn't responding.  Make sure the drive is attached, turned on,
  635. and has a formatted disk in it.
  636.  
  637. Duplicate YMODEM header received.  Ignored.
  638. A file specification block was retransmitted by the remote system, but it was
  639. not requested.  Caused by line noise, very slow responses from the sender, or
  640. operating XYZ in XMODEM mode when the sender is using YMODEM.
  641.  
  642. End of transmission not acknowledged
  643. XYZ finished sending a file using XMODEM or YMODEM, but the remote system did
  644. not answer XYZ's end of file signal.  Caused by line noise, or the remote
  645. system going down.
  646.  
  647. Enter new path:
  648. Enter the path that you want XYZ to retry the save operation on.  Hit <RETURN>
  649. without entering anything to retry on the same path.
  650.  
  651. Error closing file: <error type>
  652. XYZ closed a file that it was finished with, but a disk error occurred.  Look
  653. up the error type in this section for an explanation.
  654.  
  655. Error closing input file:  <error type>
  656. Same as above.
  657.  
  658. Error in positioning file pointer:  <error type>
  659. XYZ tries to find the end of the file after it opens it.  If it can't, you get
  660. this message.  Look up the error type that prints out to find out what error
  661. occurred.
  662.  
  663. Error in seeking to end of file
  664. Same as above.
  665.  
  666. Error opening file:  <error type>
  667. XYZ could not open a file.  Look up the error type in this section to find out
  668. what error occurred.
  669.  
  670. Error opening input file: <error type>
  671. Same as above
  672.  
  673. Error reading input file: <error type>
  674. A disk error occurred while XYZ was reading from a file.  Look up the error
  675. type in this section for an explanation.
  676.  
  677. Error seeking to end of file
  678. XYZ tries to find the end of the file after it opens it.  If it can't, you get
  679. this message.
  680.  
  681. Error seeking to offset <offset>
  682. An error occurred when XYZ tried to reference the indicated position in a
  683. file.
  684.  
  685. Error writing to file:  <error type>
  686. An error occurred while XYZ was trying to write to a file.  Look up the error
  687. type in this section to find out what error occurred.
  688.  
  689. File created on <time & date>
  690. The time the file being received was created.
  691.  
  692. File created on <time & date>, reset to <time & date>
  693. The time the file being received was created.  This will be changed to the
  694. current time and date.
  695.  
  696. File creation date not specified, reset to <time & date>
  697. The sender did not specify a creation time; therefore the current time will be
  698. put on the file.
  699.  
  700. File error
  701. A file error occurred while writing to the disk.  Caused by a full disk, a bad
  702. filename, specifying a folder that doesn't exist, or a disk error.
  703.  
  704. File error at sender
  705. A file error occurred at the remote system, so it is aborting the transfer.
  706.  
  707. File exists -- transfer resuming at offset <offset>
  708. The file that is being transferred already exists, so it is assumed that an
  709. aborted transfer is being resumed.
  710.  
  711. File <filename> exists!
  712. XMODEM and YMODEM will not overwrite a file that already exists.  Specify a
  713. different file name (XMODEM) or path (YMODEM), or delete the file that
  714. already exists.
  715.  
  716. File name is <filename>
  717. Specifies what file was being accessed when a disk error occurred.
  718.  
  719. File not found
  720. XYZ tried to read from a file that didn't exist.  Make sure that the filenames
  721. you put on the command line exist and are in the correct folder.
  722.  
  723. File pos = <position>, sender = <position>
  724. XYZ and the sender disagree over how much of the file has been sent.  The
  725. position each claims is specified.
  726.  
  727. File position error
  728. XYZ and the sender disagree over how much of the file has been sent.
  729.  
  730. Filename must be specified
  731. When doing an XMODEM download, you have to put the filename on the command
  732. line.
  733.  
  734. Function domain
  735. Function range
  736. XYZ has made a request of the ST's operating system that the ST can't handle.
  737. Either the operating system has been corrupted, or there is a bug in XYZ.
  738. Reset the computer and try again.
  739.  
  740. Fundamental error
  741. The disk drive is not responding.  Make sure that it is connected, turned on,
  742. and has a formatted disk in it.
  743.  
  744. General error
  745. This is an internal error in the ST's operating system.  You will probably
  746. have to reset the computer.
  747.  
  748. Got <type> after ZEOF
  749. The indicated packet type was received after XYZ sent a ZEOF packet.
  750.  
  751. Got a GOTCAN
  752. The remote system sent a session abort sequence (a series of CTRL-X's, or
  753. "CANcels") while XYZ was waiting for a character.
  754.  
  755. Got a session abort while waiting for ZPAD
  756. The sender sent a series of CTRL-X's, or "CANcels," while XYZ was waiting for
  757. the start of a ZMODEM frame.
  758.  
  759. Got a ZRPOS!
  760. This packet type is used for uploading, but XYZ got one when it was
  761. downloading.  Make sure that XYZ and the remote system are set to send files
  762. in the same direction.
  763.  
  764. Got a ZSKIP?!?
  765. This packet type is used for uploading, but XYZ got one when it was
  766. downloading.  Make sure that XYZ and the remote system are set to send files
  767. in the same direction.
  768.  
  769. Got: <frame type> <header> <hex bytes> CRC <CRC value>
  770. This details a ZMODEM packet that was received.
  771.  
  772. Got ZCRC '%c'
  773. This indicates tells the CRC type at the end of the last data subpacket.
  774.  
  775. Insufficient memory
  776. Either your computer does not have enough memory for XYZ to run, or something
  777. has gone wrong with the way the memory is being managed.  Try removing desk
  778. accessories and/or programs in the AUTO folder to free up some memory.  If you
  779. are running XYZ from within another program, you may have to run it from the
  780. Desktop to get enough memory.
  781.  
  782. Internal error
  783. An error has occurred within the ST's operating system.  You will probably
  784. have to reset the computer.
  785.  
  786. Invalid drive specified
  787. You specified a drive in the path name that does not exist.  Be sure the drive
  788. letter you specified was correct, and the disk is connected and turned on.
  789.  
  790. Invalid function number
  791. Invalid handle
  792. Invalid memory block address
  793. A serious internal error in XYZ or the ST's operating system has occurred.
  794.  
  795. <filename> has been renamed to <filename>
  796. A filename was specified by the sender that is incompatible with the Atari
  797. ST's operating system.  It has been transformed into a valid filename that
  798. should still be recognizable, though you may have to manually rename it before
  799. using it.
  800.  
  801. Invalid option <option>
  802. You put an option on the command line that XYZ does not recognize.  A list of
  803. the valid options is printed out.
  804.  
  805. Media change
  806. You removed the disk from the drive while XYZ was using it.  NEVER remove a
  807. floppy disk until after XYZ has finished running.
  808.  
  809. Memory free: <# of bytes>
  810. Shows the amount of memory left free before XYZ allocates its buffers.
  811.  
  812. Message: <text>
  813. The remote system sent a message.
  814.  
  815. Minimum time to transfer: <time>
  816. This indicates how long a file or files will take to transfer, assuming that
  817. the connection is 100% efficient.  Since most connections are not perfect, the
  818. actual time will probably be longer.
  819.  
  820. Missing block number
  821. A valid block number was not received.  Probably caused by line noise.
  822.  
  823. Missing or bad header
  824. The block header was not sent completely or was garbled.  Probably caused by
  825. line noise.
  826.  
  827. No files to upload were specified
  828. You selected upload, but didn't specify which files to send.  Put the
  829. filenames on the command line.
  830.  
  831. No handles left
  832. The ST has too many files open.  If you are running XYZ from within another
  833. program that opens files without closing them, this error might occur.
  834. Otherwise, it indicates an internal error in the ST's operating system.
  835.  
  836. Not enough memory to allocate buffers
  837. There isn't enough free memory to run XYZ.  Remove some of your desk
  838. accessories and/or programs in the AUTO folder, or run XYZ from the desktop
  839. rather than from within a terminal program.
  840.  
  841. Only specify one path for downloading
  842. You can only download to a single path (YMODEM and ZMODEM) or download a
  843. single file (XMODEM).
  844.  
  845. Path not found
  846. The path you specified on the command line does not exist.  All the folders in
  847. the path must have already been created before you run XYZ.  If you are using
  848. XMODEM, be sure the filename isn't the same as a folder's name.
  849.  
  850. Press any key to exit....
  851. The -p option was put on the command line, and XYZ is about to terminate.
  852. Press a key to let it complete its termination.
  853.  
  854. Range error
  855. A serious internal error has occurred within either the ST's operating system
  856. or within XYZ.
  857.  
  858. Read <number> chars from offset <offset>
  859. The amount and location of data read from a disk file is indicated.
  860.  
  861. Read fault
  862. An error occurred while the ST was trying to read from a disk.  The disk may
  863. be damaged.
  864.  
  865. Receiver canceled
  866. The remote system has aborted the transfer.
  867.  
  868. Receiver requests retransmission
  869. The remote system wants a packet resent.  Probably caused by line noise.
  870.  
  871. Receiver wants a CRC on this file but I can't do it
  872. Doing CRC checks on files isn't supported.  See WHAT IT ISN'T section.
  873.  
  874. Receiving file "<filename>", <size> bytes
  875. The transfer of a file has begun.  The size is specified by the sender, and
  876. may not be the actual size of the file.
  877.  
  878. Receiving file "<filename>", size not specified
  879. The transfer of a file has begun.  The size of the file was not specified.
  880.  
  881. Repositioning to offset <offset>
  882. The remote system wants XYZ to back up to the specified offset in the file.
  883. Probably caused by line noise.
  884.  
  885. Retrying save....
  886. XYZ is making a second attempt to save the file.
  887.  
  888. Sector not found
  889. The ST is unable to read from the disk drive.  Make sure it is connected,
  890. turned on, and has a formatted disk in it.
  891.  
  892. Seek error
  893. The ST is unable to read from the disk drive.  Make sure it is connected,
  894. turned on, and has a formatted disk in it.
  895.  
  896. Sender aborted
  897. The remote system is aborting the transfer.
  898.  
  899. Sender indicates end of file, but file length is wrong
  900. The remote system has come to the end of the file, but the number of bytes it
  901. says it sent does not match the number of bytes XYZ has received.
  902.  
  903. Sender not ready or set to receive
  904. The remote system is echoing back XYZ's packets, or it is set to upload when
  905. XYZ is set to download.  Make sure the remote system is started, and that it
  906. and XYZ are set to transfer files in the same direction.
  907.  
  908. Sender requested CRC?!?
  909. The remote system requested a file CRC check while XYZ is downloading, but
  910. that's only allowed while uploading.  Make sure the remote system and XYZ are
  911. set to transfer files in the same direction.
  912.  
  913. Sender requests retransmission
  914. The sender wants XYZ to resend a packet.  Probably due to line noise.
  915.  
  916. Sender sent ZCHALLENGE?!?
  917. The remote system issued a challenge while downloading, but this is only
  918. allowed during uploading.  Make sure XYZ and the remote system are set up to
  919. transfer files in the same direction.
  920.  
  921. Sender sent ZCOMPL -- ignored
  922. The sender indicates it completed a command, but XYZ doesn't issue commands.
  923.  
  924. Sending <number> subpacket chars:
  925. XYZ is sending a data subpacket containing the indicated number of bytes.
  926.  
  927. Sending file "<filename>", <size> bytes
  928. XYZ has started to upload the indicated file.
  929.  
  930. Sent ZBIN <type> <hex bytes> CRC <CRC value>
  931. Details of a binary-style packet that XYZ sent
  932.  
  933. Sent ZCRC '<type>' CRC <CRC value>
  934. A CRC packet was sent.
  935.  
  936. Setblock failure due to growth restrictions
  937. Something has gone wrong with the ST's memory management.
  938.  
  939. Subpacket bad CRC: <CRC value>
  940. An invalid CRC was received at the end of a data subpacket.  Probably due to
  941. line noise.
  942.  
  943. Subpacket too long
  944. A data subpacket has exceeded 1k in length, or an attention string is over 32
  945. bytes long.  Probably due to line noise.
  946.  
  947. Synchronization error
  948. The sender is sending the wrong packet.  Probably caused by either line noise
  949. or very slow responses from the sender.
  950.  
  951. Timed out
  952. Too much time has passed since the last character was received.  Probably
  953. caused by line noise, very slow responses from the sender, or failure of the
  954. sender.
  955.  
  956. To abort, press UNDO at any time
  957. This just informs you that you can abort a transfer by pressing the UNDO key.
  958.  
  959. Too many retries
  960. Too many errors have occurred.  The session is aborted.
  961.  
  962. Transfer of <filename> complete, <size> bytes
  963. Transfer of a file complete successfully.  The filename and actual size is
  964. indicated.
  965.  
  966. Unexpected ZACK from sender!
  967. This packet type is used for uploading, but XYZ got one while downloading.
  968. Make sure XYZ and the remote system are set to transfer files in the same
  969. direction.
  970.  
  971. Unknown device
  972. You didn't specify a valid drive letter in the pathname on the command line.
  973.  
  974. Unknown media
  975. The disk you are trying to use is not formatted correctly.
  976.  
  977. Usage:  xyz.ttp [options] <path>
  978. Prints in response to the -h (help) option, or an invalid option.  A list of
  979. all possible options follows.
  980.  
  981. User aborted
  982. You have pressed the UNDO key, and the session has been aborted.
  983.  
  984. Verbose mode is on!
  985. The -v option was specified.  Special debugging information will be written to
  986. the screen or a specified file.
  987.  
  988. Write fault
  989. An error occurred while XYZ was trying to write to the disk.  The disk may be
  990. damaged.
  991.  
  992. Write protect
  993. The write protect window on the floppy disk is open.
  994.  
  995. YMODEM complete!
  996. YMODEM session has completed.
  997.  
  998. YMODEM packet received, but doing XMODEM
  999. A YMODEM file specification was received, but XYZ is set to do an XMODEM
  1000. transfer.  Make sure you select the same mode for both XYZ and the remote
  1001. system.
  1002.  
  1003. YMODEM transfer aborted!
  1004. An error has occurred, and the YMODEM session is being aborted.
  1005.  
  1006. ZBIN Bad CRC: <CRC value>
  1007. An invalid CRC was at the end of a binary-style packet.  The CRC value is
  1008. specified.
  1009.  
  1010. ZEOF = 0x%lx, f_offset = 0x%lx
  1011. The sender is claiming end-of-file, but XYZ hasn't received all of it.  The
  1012. file size the sender specifies and the amount XYZ has received is printed.
  1013.  
  1014. ZFILE acked with <type>
  1015. The remote system sent the indicated packet type in response to XYZ's ZFILE
  1016. (file specification) packet.
  1017.  
  1018. ZFIN acked with <type>
  1019. The remote system sent the indicated packet type in response to XYZ's ZFIN
  1020. (end of transaction) packet.
  1021.  
  1022. ZHEX Bad CRC: <CRC value>
  1023. An invalid CRC was at the end of a hex-style packet.  The CRC value is
  1024. specified.
  1025.  
  1026. ZMODEM file transfer
  1027. A ZMODEM session has started.
  1028.  
  1029. ZMODEM transfer complete.
  1030. A ZMODEM session has completed.
  1031.